/*
 * OutputQueue.java    0.0.1    17/set/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.net.cs.server.impl;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.WritableByteChannel;

/**
 * The OutputQueue is a wrapper for the buffers containing incoming data from a channel.
 * It provides convenience methods to access the buffer and hides unnecessary operations.
 * <p>
 * This class and all the classes in this package are largely inspired to the presentation
 * "How To Build A Scalable NIO Server, Mark II" by Ron Hitchens (http://ronsoft.com)
 * </p>
 * @version    0.0.1    17/set/2009    
 * @author     Andrea Reale <andrea.reale@gmail.com>
 */
public interface OutputQueue {
    /**
     * Sends as many bytes as possibile to the destination ByteChannel. There's no guarantee
     * about the actual number of bytes sent to the channel
     * @param dest the destination channel
     * @return the actual number of bytes that were sent to <code>dest</code>
     * @throws IOException if the write on the channel encounters any problem
     */
	public int drainTo(WritableByteChannel dest) throws IOException;
	/**
	 * Checks whether the queue is empty
	 * @return true if the queue is empty
	 */
	public boolean isEmpty();
	/**
	 * Enqueues the bytes contained in the buffer <code>toEnqueue</code>. 
	 * This method should enqueue all or none of the bytes in the buffer
	 * @param toEnqueue a byte buffer containing the bytes to be enqueued
	 * @return true if all the bytes were succesfully enqueued. False otherwise.
	 */
	public boolean enqueue(ByteBuffer toEnqueue);
}
